"""
存储接口定义
===========
定义文件存储的抽象接口，支持本地文件、S3、MinIO、阿里云OSS等
"""

from abc import ABC, abstractmethod
from typing import Optional, List, Dict, Any, AsyncIterator
from datetime import datetime
from io import BytesIO


class StorageObjectInterface(ABC):
    """存储对象接口"""
    
    @abstractmethod
    def get_name(self) -> str:
        """获取对象名称"""
        pass
    
    @abstractmethod
    def get_size(self) -> int:
        """获取对象大小"""
        pass
    
    @abstractmethod
    def get_content_type(self) -> str:
        """获取内容类型"""
        pass
    
    @abstractmethod
    def get_last_modified(self) -> datetime:
        """获取最后修改时间"""
        pass
    
    @abstractmethod
    def get_metadata(self) -> Dict[str, Any]:
        """获取元数据"""
        pass
    
    @abstractmethod
    async def read(self) -> bytes:
        """读取对象内容"""
        pass
    
    @abstractmethod
    async def read_stream(self) -> AsyncIterator[bytes]:
        """流式读取对象内容"""
        pass


class StorageInterface(ABC):
    """存储接口定义"""
    
    @abstractmethod
    async def connect(self) -> bool:
        """建立连接"""
        pass
    
    @abstractmethod
    async def disconnect(self) -> bool:
        """断开连接"""
        pass
    
    @abstractmethod
    async def upload(self, bucket: str, key: str, data: bytes, 
                    content_type: str = None, metadata: Dict[str, Any] = None) -> bool:
        """上传文件"""
        pass
    
    @abstractmethod
    async def upload_stream(self, bucket: str, key: str, stream: BytesIO,
                           content_type: str = None, metadata: Dict[str, Any] = None) -> bool:
        """流式上传文件"""
        pass
    
    @abstractmethod
    async def download(self, bucket: str, key: str) -> Optional[bytes]:
        """下载文件"""
        pass
    
    @abstractmethod
    async def download_stream(self, bucket: str, key: str) -> Optional[AsyncIterator[bytes]]:
        """流式下载文件"""
        pass
    
    @abstractmethod
    async def delete(self, bucket: str, key: str) -> bool:
        """删除文件"""
        pass
    
    @abstractmethod
    async def exists(self, bucket: str, key: str) -> bool:
        """检查文件是否存在"""
        pass
    
    @abstractmethod
    async def get_object_info(self, bucket: str, key: str) -> Optional[StorageObjectInterface]:
        """获取对象信息"""
        pass
    
    @abstractmethod
    async def list_objects(self, bucket: str, prefix: str = "", 
                          max_keys: int = 1000) -> List[StorageObjectInterface]:
        """列出对象"""
        pass
    
    @abstractmethod
    async def create_bucket(self, bucket: str) -> bool:
        """创建存储桶"""
        pass
    
    @abstractmethod
    async def delete_bucket(self, bucket: str) -> bool:
        """删除存储桶"""
        pass
    
    @abstractmethod
    async def bucket_exists(self, bucket: str) -> bool:
        """检查存储桶是否存在"""
        pass
    
    @abstractmethod
    async def get_presigned_url(self, bucket: str, key: str, expires_in: int = 3600) -> str:
        """获取预签名URL"""
        pass
